package com.gobang.service;

import com.gobang.domain.entity.MatchQueueEntry;

import java.util.List;

/**
 * 匹配队列管理器接口
 * 负责匹配队列的数据管理和操作
 *
 * @author gobang-team
 * @since 1.0.0
 */
public interface QueueManager {

    /**
     * 加入匹配队列
     *
     * @param userId 用户ID
     * @param currentScore 用户当前积分
     * @return 队列位置（从1开始）
     */
    int addToQueue(Long userId, Integer currentScore);

    /**
     * 从匹配队列中移除用户
     *
     * @param userId 用户ID
     * @return 是否成功移除
     */
    boolean removeFromQueue(Long userId);

    /**
     * 检查用户是否在队列中
     *
     * @param userId 用户ID
     * @return 是否在队列中
     */
    boolean isInQueue(Long userId);

    /**
     * 获取用户在队列中的位置
     *
     * @param userId 用户ID
     * @return 队列位置，不在队列中返回-1
     */
    int getQueuePosition(Long userId);

    /**
     * 获取队列大小
     *
     * @return 队列中等待的用户数量
     */
    int getQueueSize();

    /**
     * 获取等待队列中的所有用户
     *
     * @return 等待用户列表
     */
    List<MatchQueueEntry> getWaitingUsers();

    /**
     * 获取指定数量的等待用户
     *
     * @param limit 数量限制
     * @return 等待用户列表
     */
    List<MatchQueueEntry> getWaitingUsers(int limit);

    /**
     * 批量移除用户
     *
     * @param userIds 用户ID列表
     * @return 成功移除的用户数量
     */
    int removeUsersFromQueue(List<Long> userIds);

    /**
     * 清理超时用户
     * 移除等待时间超过指定阈值的用户
     *
     * @param timeoutSeconds 超时时间（秒）
     * @return 清理的用户数量
     */
    int cleanupTimeoutUsers(long timeoutSeconds);

    /**
     * 获取队列统计信息
     *
     * @return 队列统计信息
     */
    QueueStatistics getQueueStatistics();

    /**
     * 获取用户的队列条目信息
     *
     * @param userId 用户ID
     * @return 队列条目信息，不在队列中返回null
     */
    MatchQueueEntry getUserQueueEntry(Long userId);

    /**
     * 更新用户在队列中的信息
     *
     * @param userId 用户ID
     * @param currentScore 更新后的积分
     * @return 是否更新成功
     */
    boolean updateUserInQueue(Long userId, Integer currentScore);

    /**
     * 队列统计信息
     */
    class QueueStatistics {
        private final int totalUsers;
        private final long avgWaitTime;
        private final int minScore;
        private final int maxScore;
        private final double avgScore;

        public QueueStatistics(int totalUsers, long avgWaitTime, int minScore, int maxScore, double avgScore) {
            this.totalUsers = totalUsers;
            this.avgWaitTime = avgWaitTime;
            this.minScore = minScore;
            this.maxScore = maxScore;
            this.avgScore = avgScore;
        }

        public int getTotalUsers() { return totalUsers; }
        public long getAvgWaitTime() { return avgWaitTime; }
        public int getMinScore() { return minScore; }
        public int getMaxScore() { return maxScore; }
        public double getAvgScore() { return avgScore; }

        @Override
        public String toString() {
            return String.format("QueueStatistics{users=%d, avgWait=%ds, scoreRange=%d-%d, avgScore=%.1f}", 
                    totalUsers, avgWaitTime, minScore, maxScore, avgScore);
        }
    }
} 